Libris Britannia 4/science library(b).zip/science library(b)/INFO/QHELP.ZIP/QHELP.DOC

Text File | 1988-04-30 | 18KB | 372 lines

                          QHELP - PopUp Help Program
                                  Users Guide



                                  Written by

                                Mark VanKekerix
                                 2035 J Apt 6
                               Lincoln NE  68510
                                [phone]



         QHELP and QHCOMPIL software Copyright 1988 by Mark VanKekerix








                               TABLE OF CONTENTS

     License
     Introduction
          What is QHELP?
          The Story Behind QHELP
          System Requirements
     Using QHELP
          What Are Keywords?
          Installing QHELP
          Popping Up the Help Screen
          Moving Through the Help File
          Changing Help Files
          Removing QHELP from Memory
          Notes for Floppy Disk Users
     Acknowledgments


NOTE:     In this document, QHELP refers to the resident program QHELP.EXE,
          and QHCOMPIL refers to the help file compiler program
          QHCOMPIL.EXE.  Although QHCOMPIL is referred to in this guide,
          information on creating help files with QHCOMPIL is contained in a
          separate document.  QHCOMPIL and the QHCOMPIL documentation may not
          have been included with your copy of QHELP.





                                    LICENSE

Users of the QHELP system are granted a limited license for personal use.  No
part of the QHELP system can be distributed for profit without a specific
written agreement (this includes distribution within a company or
corporation, "bundling" with other software, etc.).  These limitations apply
to QHELP, QHCOMPIL (the help file compiler), and any help files created with
QHCOMPIL.

What this means is you are free to use QHELP and any help files you have
created yourself or obtained from bulletin boards, etc., but if you want to
package QHELP with another program you are selling for profit, contact me for
written permission to do so (I will ask for a small fee for such a license).

The limitation on "bundling" QHELP with other programs applies only if the
program is being sold for profit.  If you have developed a public domain
program and would like to use QHELP and a help file you have written as the
program's help system, please feel free to do so.

If you have written a help file for any program (public domain or otherwise)
that you think other people would find helpful, I encourage you to make it
part of the public domain (along with a copy of QHELP).

I also encourage you to upload QHELP to all of your favorite bulletin boards,
copy it for your friends, etc., as long as you don't violate the above
restrictions.

QHELP may be distributed by itself (without QHCOMPIL) subject to the above
restrictions.  If you are going to distribute QHELP in such a manner, please
make sure this document and at least one compiled help file is included.






                                 INTRODUCTION


What is QHELP?

     QHELP is a memory resident help system that can pop up in most any text-
     based application program.  The file containing the available help
     information is called the "help file", and is fully user-definable.
     Anyone that has an ordinary text editor and a copy of QHCOMPIL (the help
     file compiler) can create his/her own help files.  The help files can be
     very large, but QHELP will always use the same small amount of memory
     regardless of the size of the help file.  QHELP does this by only
     holding a list of topic names (called "keywords") in memory; For the
     actual help information it returns to the file.


The Story Behind QHELP

     A long time ago on a PC far, far away, I was a lowly Pascal language
     programmer who desperately wanted to learn a new language called "C" and
     write hot new programs that would take the world by storm...

     Actually it wasn't all that long ago and "C" isn't such a new language,
     but I decided it was about time I learned to use it, so I started
     writing simple programs and such using Borland International's TurboC
     compiler.  Before too long I thought I was ready to start a major
     program, but I couldn't decide what to write.  I wanted to write
     something for the public domain, but most of the really useful ideas I
     had had already been written by someone else.  Then I came up with the
     idea for QHELP.

     TurboC has a really nice help system.  It can give information on any
     topic relating to the use of its integrated development environment,
     including menu options, use of the editor, and "C" reserved words and
     standard library functions.  The problem was that I didn't use the
     integrated environment very often; I have another editor that is more
     powerful than TurboC's (it allows editing of multiple files, definition
     of macros, etc.) but when I used it I couldn't access TurboC's help
     system.  So I decided to write a "pop up" help program that could give
     me the help information I wanted from within any editor I chose to use.
     Since I wanted to be able to add to or change the help information, I
     made QHELP general enough that it could give help on any topic that
     someone had written a help file for.

     QHELP is very much patterned after TurboC's help system.  I really liked
     the way Borland set it up; When popped up, the help system tried to find
     information on whatever word happened to be at the cursor, but if it
     couldn't find anything it would present a menu of topics.  Also, if
     there were topics relating to the topic you were looking at it allowed
     you to go to those topics by simply pointing at the topic name.  I
     decided to incorporate these features, plus a few of my own, into QHELP.


System Requirements

     QHELP will run on IBM PC, XT, or AT (or compatible) computers using MS-
     DOS 2.0 or later.  It takes up about 35K of memory when resident.  QHELP
     doesn't care what display card you are using, but it will only pop up in
     text modes (not in graphics modes).




                                  Using QHELP

What Are Keywords?

     Keywords are the basis for retrieval of help information.  A help file
     for QHELP is simply a list of "key words" that identify the topics
     available in the help file, along with a description for each topic (the
     actual help information) and the names of topics that are related.

     For example, if the help file contained information on MS-DOS system
     commands, the word "chdir" would be a keyword (since it is the DOS
     command for changing directories).  "chdir" would be listed in the help
     file as a keyword, along with a description of what the command does.
     Along with the description would be a list of related keywords, such as
     "mkdir","rmdir", and "dir" (the commands for creating, removing, and
     listing directories).

     When QHELP is "popped up", it looks at the word on the screen next to
     the cursor and tries to find that word in its list of keywords.  If it
     finds a keyword, the description for that keyword is put on the screen,
     along with any related keywords.  You are then allowed to select one of
     the related keywords (in which case the description for the selected
     keyword replaces the original one) or return to the application you are
     using.

     If QHELP can't find a keyword that matches the word at the cursor, it
     pops up a "default screen", usually a menu of available keywords.


Installing QHELP

     Installing QHELP is fairly simple.  At the DOS prompt, give the
     following command:

          QHELP <filename>

     where <filename> is replaced by the name of the help file you want to
     use.  The help file name should not contain an extension; An extension
     of ".QHP" is assumed.  For example, the command "QHELP TESTFILE" would
     install QHELP with the keyword list from the file "TESTFILE.QHP".
     "TESTFILE.QHP" would have to be in the current directory, or QHELP will
     not install and will instead report that it can't find the specified
     help file.  Another way to install QHELP is to specify the full path and
     filename for the help file, as in "QHELP C:\QHFILES\TESTFILE", which
     would install QHELP with the keyword list from the file "TESTFILE.QHP",
     located in the QHFILES subdirectory of drive C:.

     If the specified help file is in the current directory when QHELP is
     installed, or if you have specified the full pathname for the help file,
     then QHELP will always be able remember where the help file is so it can
     properly retrieve help information.  If a partial pathname is specified,
     as in "QHELP ..\TESTFILE" (which specifies the file "TESTFILE.QHP" in
     the directory above the current one), then QHELP will not be able to
     locate the file properly if you change directories (since "TESTFILE.QHP"
     will not always be located in the directory "above" the current one).

     If QHELP can find the help file you specified, it will print a message
     telling you that it is installing, and list for you the "hot key"
     combination that will cause it to pop up.




Popping Up the Help Screen

     To obtain help information while running an application program, press
     the "hot key" combination that QHELP gave to you when it installed.  For
     example, if the hot key was "[Alt][Ctrl]-H", then press and hold the
     "Alt" key, press and hold the "Ctrl" key, and tap the "H" key.  The
     QHELP window will then appear in the middle of your screen, and you can
     release all the keys you're holding down.

     As it is popping up, QHELP will look at the word under the cursor and
     attempt to find that word in its list of keywords.  The cursor MUST be
     positioned properly (on some part of the word) for QHELP to find that
     word.  If it finds the word in its keyword list, then QHELP will display
     in its window the description for that keyword.  If it can't find the
     word, then QHELP will display the "default screen" for the help file,
     which is usually a list available keywords.

     If QHELP detects that your system is capable of displaying colors, the
     QHELP window will appear in the colors defined by the author of the
     help file.  If your system appears to be monochrome, the window will
     be displayed in QHELP's default black and white color scheme.  When using
     a monochrome-type display with a color display adapter (like the
     composite display and CGA adapter of older Compaq portable computers)
     you may want to give the command "MODE BW80" at the DOS prompt to change
     your system to a video mode that QHELP will recognize as black and white.


Moving Through the Help File

     The help information for a keyword may be longer than the window that
     QHELP displays it in.  If this is the case, the word "PgDn" will appear
     in the lower right corner of the QHELP window, indicating that there is
     more information than will fit in the window and that you can use the
     <PgDn> key on the numeric keypad to display the next "page" of
     information.  When you press <PgDn>, the next page will be displayed,
     and the word "PgUp" will appear in the upper right corner of the window,
     indicating that there are page(s) of information "above" the page
     currently in the window.  If there are several pages of information, the
     "PgUp" and "PgDn" indicators may both be displayed at the same time.

     The help information text will be displayed in an appropriate color.  If
     there are keywords related to the information you are currently looking
     at, these related keywords will be displayed in a different color.  One
     of these related keywords will also be displayed in a "highlight" color,
     indicating that it is the "selected" related keyword.  By using the
     arrow keys on the numeric keypad, you can change the selected keyword to
     any one of the related keywords being displayed.  The right arrow key
     moves the "highlighter" to the next keyword to the right, the left arrow
     moves left, the up arrow moves up, and the down arrow moves down (pretty
     much as you would expect).

     Pressing the <Enter> key will cause the text in the window to be
     replaced with the information on the currently highlighted keyword.  In
     this way, you can go directly to related topics.

     Pressing the <F1> key at any time will display the "default screen" for
     the help file (this is usually a list of available keywords).  This is
     the same screen that would appear if QHELP was unable to find a keyword
     at the cursor when popped up.

     Pressing the [Alt]-F1 key combination will "back up" to the information
     on the keyword you last examined.  For example, if you were looking at a
     description of the DOS "chdir" command, selected the related topic
     "mkdir", then pressed [Alt]-F1, you would be returned to the description
     of "chdir".  QHELP remembers the last ten keywords you examined, and so
     allows you to back up ten times.  If you have reached the limit of what
     QHELP remembers, no action is taken when you press [Alt]-F1.

     Pressing the <ESC> key will return you to your application program.




Changing Help Files

     If you have popped QHELP up and realize that the information you seek is
     in a different help file than the one you installed, you must change
     help files.  To do this, press the <F2> key.  QHELP will prompt you for
     the name of the help file you wish to load.  When entering the help file
     name, don't give an extension (".QHP" is assumed).  It is usually best
     to specify the complete pathname for the file (including the drive
     letter).

     If QHELP is unable to locate the help file, it will tell you so, then
     return you to the keyword description that was in use when you pressed
     the <F2> key.

     If QHELP finds the help file, it will tell you the "hot key" associated
     with that file (which may be different from the original one).  This is
     now the key combination that will pop QHELP up.  The default screen for
     the new file will then be displayed.


Removing QHELP from Memory

     If you wish to remove QHELP from memory, issue the following command at
     the DOS prompt:

          QHELP /U

     QHELP will check to see if it is resident in memory, and attempt to
     unload the resident portion if it is.  If QHELP is not resident, it will
     tell you so.

     It is always a good idea to release all resident programs from memory in
     the reverse of the order in which they were installed, i.e., the last
     resident program should be released first, the next to last program
     second, etc.  If you don't do this, you might end up with "holes" in
     memory, or worse yet, interrupt vector chains corrupted (this can cause
     your system to lock up among other things).  QHELP will try to determine
     if other resident programs are loaded above it, and will refuse to
     release itself if it finds any, but it isn't always accurate.  The best
     defense against such problems is to release all resident programs above
     QHELP before releasing QHELP itself.


Notes to Floppy Disk Users

     If you are running QHELP from floppy disks, the floppy disk containing
     the help file must be in the same disk drive that it was in when QHELP
     was installed, or QHELP will be unable to locate its help information.
     You can remove the disk when QHELP is inactive, but the disk MUST be
     present when QHELP is popped up.  If you inadvertently pop QHELP up
     without the disk in its proper drive, QHELP will give an error message,
     and you will have to press <ESC> (to exit QHELP), put the disk in the
     correct drive, and pop QHELP up again.




                                Acknowledgments


I would like to thank Borland International both for its outstanding "C"
compiler, TurboC, and for the excellent help system in TurboC's integrated
development environment which inspired me to write QHELP.

I would also like to thank Al Stevens for his article "Writing Terminate-and-
Stay-Resident Programs (Part 1: TSRs in TurboC)" in Computer Language
magazine (February 1988 issue).  In that article Mr. Stevens gave complete
listings for the shell of a resident program, and these are the residency
routines that QHELP uses (with some minor modifications).  Anyone interested
in trying his/her hand at writing resident programs (in "C" or otherwise)
would do well to read Mr. Stevens' article.

Also, special thanks go out to my roommate, Dave Steiner.  Since he is an
experienced "C" programmer and has also written many resident programs (in
several languages), I pestered him with endless questions and he somehow
managed to answer them all.